home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 November / Macworld (1999-11).dmg / Updaters / WhiteCap 3.0.4 / WhiteCap Source.sit / WhiteCap Source / Common / General Tools / Headers / UtilStr.h < prev    next >
C/C++ Source or Header  |  1999-07-13  |  12KB  |  256 lines
  1. #pragma once
  2.  
  3. #ifndef _CUTILSTR_
  4. #define _CUTILSTR_
  5.  
  6.  
  7. #ifndef NULL
  8. #define NULL 0L
  9. #endif
  10.  
  11. #include "Hashable.h"
  12.  
  13.  
  14. class CEgIStream;
  15. class CEgOStream;
  16.  
  17. //    This is versitile string class, optimized for all string sizes
  18. class UtilStr : public Hashable {
  19.  
  20.  
  21.     public:                        
  22.                                     UtilStr();
  23.                                     UtilStr( const char* inCStr );
  24.                                     UtilStr( const unsigned char* inStrPtr );
  25.                                     UtilStr( const UtilStr& inStr );
  26.                                     UtilStr( const UtilStr* inStr );
  27.                                     UtilStr( long inNum );
  28.                                     UtilStr( const void* inPtr, long numBytes );
  29.         virtual                        ~UtilStr();
  30.                                 
  31.         //    *** Assign ***
  32.         //    Post:    This UtilStr empties itself and appends the argument (ie it copies the argument)
  33.         inline void                    Assign( const char* inCStr )                                { mStrLen = 0; Append( inCStr );                }
  34.         void                        Assign( const unsigned char* inStrPtr );
  35.         void                        Assign( const UtilStr* inStr );
  36.         void                        Assign( const UtilStr& inStr );
  37.         void                        Assign( long inNum );
  38.         void                        Assign( char inChar );
  39.         void                        Assign( const void* inPtr, long numBytes );
  40.         void                        Assign( CEgIStream& inStream, long numBytes );
  41.         
  42.         //  *** Append ***
  43.         //    Post:    The argument is appended to this string
  44.         void                        Append( const char* inCStr );
  45.         inline void                    Append( const unsigned char* inStrPtr );
  46.         inline void                    Append( char inChar )                                        { Append( &inChar, 1 );                            }
  47.         void                        Append( long inNum );
  48.         inline void                    Append( const UtilStr* inStr );
  49.         inline void                    Append( const UtilStr& inStr )                                { Append( inStr.getCStr(), inStr.length() );    }
  50.         void                        Append( const void* inSrce, long numBytes ); 
  51.         
  52.         //    *** Operators ***
  53.         //    The + signifies Append() an append and the = signifies Assign()
  54.         UtilStr                        operator + ( const UtilStr& inStr );
  55.         UtilStr                        operator + ( const char* inCStr );
  56.         UtilStr                        operator + ( const long inNum );
  57.         UtilStr&                    operator = ( const UtilStr& inStr );
  58.         
  59.         
  60.         //    Post:                    Makes the length of this <numBytes>.
  61.         //    Note:                    The data in this is garbage!
  62.         inline void                    Dim( unsigned long numBytes )                        { Assign( (void*) NULL, numBytes );        }
  63.         
  64.         //    Post:    Swaps the internal string ptrs.  This fcn is useful if you need to assign a string value and don't care
  65.         //            if the original string changes.
  66.         void                        Swap( UtilStr& ioStr );
  67.  
  68.         //    Post:    The length of this string is returned
  69.         inline unsigned long        length() const                                        { return mStrLen;                        }
  70.         
  71.         //    Post:    Returns the <i>th character in this string.  If i < 1 or greater than len, 0 is returned
  72.         char                        getChar( unsigned long i ) const;
  73.         
  74.         //    Post:    The <i>th character is replaced with <inChar>.  If i < 1 or greater than len, this
  75.         //            string is unaffected.
  76.         void                        setChar( unsigned long i, char inChar );
  77.  
  78.         //    Post:    <inStr> is appended to the beginning to this string.
  79.         void                         Prepend( const char inChar);
  80.         void                        Prepend( const char* inStr );
  81.         void                        Prepend( UtilStr& inStr );
  82.         
  83.         //    Post:    <inSrce> (or <inNum>) is inserted in the string after the <inPos>th character
  84.         //    Note:    When <inPos> = 0, this is the same as Prepend(...)
  85.         //    Note:    If <inPos> is greater then or equal to the length of this str, <inSrce> is appended to the end
  86.         //            "HiFred".Insert( 2, "," )  --->  "Hi,Fred"
  87.         void                        Insert( unsigned long inPos, const UtilStr& inSrce );
  88.         void                        Insert( unsigned long inPos, const char* inSrce, long inSrceLen );
  89.         void                        Insert( unsigned long inPos, char inChar, long inNumTimes );
  90.         void                        Insert( unsigned long inPos, long inNum );
  91.                 
  92.         //    Post:    Returns a ptr to a pascal style string of this string.  Remember that if this string is greater than
  93.         //            255 chars, only the first 255 can be accessed.  *NOTE: This fcn is designed for
  94.         //            instantanious use (ie, if you change the string at all, you *must* re-call this method).  In other words,
  95.         //            treat the ptr returned as *read* only!
  96.         unsigned char*                getPasStr() const;
  97.         
  98.         //    Post:    Returns a ptr to a C style string of this string.  *NOTE: This fcn is designed for
  99.         //            instantanious use (ie, if you change the string at all, you *must* re-call this method). In other words,
  100.         //            treat the ptr returned as *read* only!
  101.         char*                        getCStr() const;
  102.         
  103.         //    Post:    This string is emptied (length is zero)
  104.         inline void                 Wipe()                                                        { mStrLen = 0;        }
  105.         
  106.         //    Post:    Replaces all instances of <inTarget> with <inReplacement>
  107.         void                        Replace( char inTarget, char inReplacement );
  108.         
  109.         //    Post:    Truncates <numToChop> chars from this string, either from the right or left.  If <numToChop> is
  110.         //            less than 1, this string is unaffected.  If <numToChop> is greater or equal to the length
  111.         //            if this string, the string is emptied.
  112.         void                        Trunc( unsigned long numToChop, bool fromRight = true );
  113.         
  114.         //    Post:    At position <inPos> in the string, <inNum> characters are removed
  115.         //            "Hi,Fred".Remove( 3, 1 )  --->  "HiFred"
  116.         void                        Remove( unsigned long inPos, unsigned long inNum );
  117.         
  118.         //    Post:    All instances of a given string are removed from this string
  119.         //    Note:    inLen is the length of inStr.  If inLen < -1, the length of inStr is calculated
  120.         void                        Remove( char* inStr, int inLen = -1, bool inCaseSensitive = true );
  121.         
  122.         //    Post:    Truncates after the <inNumToKeep>th character.  If <inNumToKeep> is greater than or equal to
  123.         //            the length, nothing happens.
  124.         void                        Keep( unsigned long inNumToKeep );
  125.         
  126.         //    Post:    If this' len is larger than <inMaxLen>, a '…' replaces the <inPos>th character and chars are removed 
  127.         //            after the '…' until the this' length is <inMaxLen>
  128.         void                        PoliteKeep( unsigned long inMaxLen, unsigned long inPos );
  129.  
  130.         //    Post:    A simple filter that decapitalized all chars that aren't the first in each word.
  131.         void                        Decapitalize();
  132.         
  133.         //    Post:    Capitalizes all the chars in this string.
  134.         void                        Capitalize();
  135.         
  136.         //    Post:    Removes any leading spaces in this string. 
  137.         void                        ZapLeadingSpaces();
  138.         
  139.         //    Pre:    <pasDestPtr> points to a pascal string of length <inBytesToCopy>
  140.         //    Post:    The contents of this string is copied to <pasDestPtr>, updating its length byte
  141.         void                        copyTo( unsigned char* pasDestPtr, unsigned char inBytesToCopy ) const;
  142.         
  143.         //    Pre:    <cDestPtr> points to a c string with an allocated length of <inBytesToCopy>
  144.         //    Post:    The contents of this string is copied to <cDestPtr>, appending the NUL byte
  145.         void                        copyTo( char* cDestPtr, unsigned long inBytesToCopy ) const;
  146.         
  147.         //    Post:    This string is read from <inFile> from the current file position
  148.         void                        ReadFrom( CEgIStream* inStream );
  149.         
  150.         //    Post:    This string writes itself to <inStream> at the current file position
  151.         void                        WriteTo( CEgOStream* inStream ) const;
  152.         
  153.         //    Post:    Returns the rational value of this string times <inMultiplier>.  All chars not '0'..'9' are
  154.         //            ignored, except a leading '-' and a '.', where the digits that follow are decimal digits
  155.         //    Usage:    "12.34".GetValue( 20 ) will return 246
  156.         long                        GetValue( long inMultiplier = 1 ) const;
  157.         
  158.         //     Post:    Returns a floating point value of this string
  159.         double                        GetFloatValue() const;
  160.                 
  161.         //    Pre:    <inDivisor> != 0
  162.         //            <inNumDecPlaces> < 8
  163.         //    Post:    Assigns the string equivilent of <inVal>/<inDivisor> to this string, truncating the string
  164.         //            after <inNumDecPlaces> decimal places.
  165.         //    Usage:    SetValue( 24686, 20, 2 ) would assign this string to "12.34"
  166.         void                        SetValue( long inVal, long inDivisor = 1, int inNumDecPlaces = 5 );
  167.         
  168.         //    Post:    Assigns this string the roman numeral string for the number <inValue>.
  169.         void                        SetRomanValue( long inValue );
  170.         
  171.         //    Post:    Returns the character position within this string of the rightmost occurance of <c>. If
  172.         //            <c> is not found, 0 is returned.
  173.         inline long                    FindLastInstanceOf( char c ) const                        { return FindPrevInstanceOf( mStrLen, c );        }
  174.  
  175.         //    Post:    Returns the character position within this string of the leftmost occurance of <c> after pos <inPos>. 
  176.         //            If <c> is not found, 0 is returned.      
  177.         long                        FindNextInstanceOf( long inPos, char c ) const;
  178.  
  179.         //    Post:    Returns the character position within this string of the rightmost occurance of <c> after pos <inPos>. 
  180.         //            If <c> is not found, 0 is returned.      
  181.         long                        FindPrevInstanceOf( long inPos, char c ) const;
  182.         
  183.         //    Post:    Compares this str with <inStr> and returns:
  184.         //            "hi".compareTo( "hi", 3, true ) == 0
  185.         //            "a".compareTo( "z", 2, true ) < 0
  186.         //            "Z".compareTo( "a", 2, false ) > 0
  187.         int                            compareTo( const UtilStr* inStr,            bool inCaseSensitive = true ) const;
  188.         int                            compareTo( const unsigned char* inPStr,     bool inCaseSensitive = true ) const;
  189.         int                            compareTo( const char* inCStr,                 bool inCaseSensitive = true ) const;
  190.  
  191.  
  192.         //    Post:    Compares the first <inN> chars of data at <s1> and <s2> and returns:
  193.         //            StrCmp( "hi", "hi", 3, true ) == 0
  194.         //            StrCmp( "a", "z", 2, true ) < 0
  195.         //            StrCmp( "z", "a", 2, true ) > 0
  196.         //    Note:    If <inN> < 0, the length of s1 (as a C string) is used.
  197.         //    Note:    StrCmp( *, *, 0, * ) always returns false.
  198.         static int                    StrCmp( const char* s1, const char* s2, long inN, bool inCaseSensitive );
  199.                 
  200.         //    Post:    Returns the 1st next instance of <inStr> in this str, skipping the first inStartingPos chars.   If an instance cannot be found, 0 is returned.
  201.         //    Note:    inLen is the length of inStr.  If inLen < -1, the length of inStr is calculated
  202.         //            "Hi,Fred".contains( "fred", false ) == 4
  203.         inline long                 contains( const UtilStr&    inStr,                    int inStartingPos = 0,    bool inCaseSensitive = true ) const            { return contains( inStr.getCStr(), inStr.length(), inStartingPos, inCaseSensitive );    }        
  204.         long                         contains( const char*        inStr, int inLen = -1,    int inStartingPos = 0,     bool inCaseSensitive = true ) const;        
  205.         
  206.         //    Post:    Blockmoves memory
  207.         static void                    Move( void* inDest, const void* inSrce, unsigned long inNumBytes ); 
  208.  
  209.         //    Post:    Appends <inStr>, exporting/translating <inData> to "meta" format (ie, all translated bytes >= 32 or <= 127)
  210.         void                        AppendAsMeta( const UtilStr* inData );
  211.         void                        AppendAsMeta( const void* inData, long inLen );
  212.         
  213.         //    Post:    Appends <inStr>, importing/translating <inStr> from "meta" format.
  214.         //    Note:    See AppendAsMeta()
  215.         //    Ex:        s.Wipe(); t.Wipe();                                // Empty our strings s and t
  216.         //            s.AppendAsMeta( dataPtr, 5 );                     // Encode some data and put it in s
  217.         //            t.AppendFromMeta( s.getCStr(), s.length() );    // t now contains exactly what was in dataPtr                
  218.         void                        AppendFromMeta( const UtilStr* inStr );
  219.         void                        AppendFromMeta( const void* inStr, long inLen );
  220.         
  221.         // Post:    Returns a psudorandom long for this string
  222.         long                        Hash() const;
  223.         
  224.         // Must be defined as a Hashable
  225.         bool                        Equals( const Hashable* inComp ) const;
  226.         
  227.         
  228.         
  229.         // Pre:        inB1 and inB2 are '0' to '9', 'A' to 'F', or 'a' to 'f'
  230.         // Post:    The corresponding byte value is appended to this string
  231.         void                        AppendHex( char inB1, char inB2 );
  232.  
  233.         // Post:    Returns a floating point number for the given ASCII chars
  234.         static double                GetFloatVal( char* inNumStr, long inLen );
  235.         
  236.         //    Post:    Returns the truncated signed long value of this string.  All characters not '0'..'9' are ignored
  237.         //            except a leading '-'
  238.         //            <*outPlacePtr> is set to 10^( 1 + trunc( log10( <strVal> ) ) )
  239.         //    Usage:    "12.9".GetIntValue( &i ) returns 12 and assigns i to 100
  240.         static long                    GetIntValue( char* inStr, long inLen, long* outPlacePtr = NULL );
  241.  
  242.     protected:
  243.         unsigned long                mBufSize;                 // Physical size of buf
  244.         unsigned long                mStrLen;                // NOTE: ALWAYS holds string size
  245.         char*                        mBuf;                    // Holds ptr to str data
  246.         
  247.         void                        init();
  248.  
  249.         friend class UtilStr;
  250. };
  251.  
  252.  
  253.  
  254.  
  255. #endif
  256.